feat(pi,omp): add runtime model fallback - #2358

Adds runtime model fallback for the Pi and OMP hosts. Design split by host: OMP uses its native retry.fallbackChains (per-role, with dedicated chains for the GPT-pinned roles to avoid OMP's positional candidate selection stranding them at chain tails), and Pi — which has no built-in support — ships a self-contained extension with the previously-shared policy inlined into config/pi/fallback.ts. Pi's chain has been repointed to all-free-tier CLIProxy models.

• Pi fallback chain: [cliproxyapi/gemma-4-31b-it, cliproxyapi/glm-4.7, cliproxyapi/free] — all zero-cost. gemma-4-31b-it and free (router-fallback) are added to config/pi/models.json and .tpl.json. glm-4.7 is Pi's default model but including it in the chain is safe because onError filters ref !== currentRef before selecting.
• Pi extension (config/pi/fallback.ts): per-field parseFallbackConfig, chain-walking loop that cools and skips unselectable candidates, transactional pendingRestore/confirmRestore, ctx.model vs appliedRef diff for manual-switch detection, timeout_seconds omitted.
• OMP native chains (config/omp/config.yml + .tpl.yml): retry.modelFallback: true, retry.fallbackRevertPolicy: "cooldown-expiry", explicit chains for default and slow/vision/plan (avoiding the positional-tail zero-candidate problem in findRetryFallbackCandidates).
• Spec (spec/llm_update_spec.sh): asserts Pi chain composition, every Pi fallback ref resolves against config/pi/models.json (guards against unregistered refs cooling the whole chain), Pi schema keys ⊂ OpenCode keys with delta exactly ["timeout_seconds"], Pi self-containment (no config/shared/fallback), OMP native config values via yq, and a positional-invariant assertion that no modelRole sits at the last index of its inherited chain (checked by both exact and base selector).

• onSuccess clears primaryRef before the caller confirms the restore actually succeeded. If selectRef(restore) returns false, the primary is silently lost — the session stays on the fallback model with no way to re-arm the restore. (fixed by commit fface40)
• try/catch around host.on("model_select", …) is dead code — Pi accepts the handler natively and OMP unconditionally accepts any event string via handlers.set(...) without throwing. The catch and its comment are misleading defensive code. (fixed by commit fface40)
• loadFallbackConfig uses a Partial<FallbackConfig> type assertion, not runtime validation — a syntactically-valid JSON with wrong types (e.g., "fallback_models": "gpt", "retry_on_errors": null) will parse cleanly, slip past the catch, and later throw inside agent_end (.some, .find, .includes on non-arrays), killing the very turn the extension is supposed to rescue. (fixed by commit fface40)
• Fallback stops after the first setModel rejection instead of trying the next candidate: when selectRef returns false the handler cools the target down, notifies once, and returns — no sendMessage, no next-model attempt. A single unregistered/keyless fallback model thus swallows the entire chain until the user manually retries. (fixed by commit 88eca69)
• timeout_seconds is declared in FallbackConfig, defaulted to 30, and shipped in all three fallback JSON files, but no code path in createFallbackPolicy or attachFallback ever reads it — the setting is silently ignored. Either wire it into the fallback flow (e.g., wrap setModel/sendMessage in an AbortSignal.timeout) or drop the field so the shared schema stops advertising unimplemented behavior. (fixed by commit fface40)
• On OMP, a user's manual model switch can be silently overwritten by the restore path: OMP's ExtensionAPI never emits model_select (only internal model_changed), so noteManualSelection never fires. After a fallback armed primaryRef=A, if the user manually picks C, the next successful turn past A's cooldown will restore A on top of C. (fixed by commit fface40)
• The new Describe 'Pi and OMP runtime fallback' block in spec/llm_update_spec.sh isn't closed before the pre-existing OMP CLIProxy/DeepSeek/OpenRouter tests, so the closing End at line 218 swallows eight unrelated cases into this Describe. (fixed by commit fface40)

Summary by CodeRabbit

• New Features

  • Added automatic model fallback for Pi and OMP when configured provider or HTTP errors occur.
  • Supports ordered fallback models, retry limits, cooldowns, timeouts, and notifications.
  • Automatically resumes with the primary model after a successful cooldown.
  • Added configurable fallback settings with template-based installation.

• Bug Fixes

  • Prevents fallback policy files from being loaded as extensions.
  • Excludes default models from fallback chains.

Walkthrough

Adds shared runtime fallback policy logic and integrates it with Pi and OMP. The change adds configurable retry rules, model cooldowns, fallback switching, continuation turns, Home Manager installation, template generation, and validation tests.

Changes

Runtime fallback

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Provider
  participant RuntimeFallback
  participant FallbackPolicy
  participant PiOrOMP
  Provider->>RuntimeFallback: provider response
  RuntimeFallback->>FallbackPolicy: classify status or error
  FallbackPolicy-->>RuntimeFallback: fallback decision
  RuntimeFallback->>PiOrOMP: select fallback model
  PiOrOMP-->>RuntimeFallback: model selection result
  RuntimeFallback->>PiOrOMP: dispatch continuation turn

Poem

I’m a rabbit with a fallback trail,
When one model fails, I hop without fail.
Cooldowns mark the paths I know,
Pi and OMP help the next turn flow.
Configured carrots guide me where to go.

• X
• Mastodon
• Reddit
• LinkedIn